Shareware Overload Trio 2/Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO/dir27/grphca22.zip/GRAPHICA.DOC

Text File | 1993-02-03 | 43KB | 1,274 lines

GRAPHICA v2.2
A System for Drawing Scientific Graphs

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

User's Manual

by Antonio Montes

3 February 1993


(C) Copyright 1992,1993 Antonio Montes.
Portions (C) Copyright 1991 Borland International.

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

If you like this program, you can send a contribution to the
address near the end of this file.  The version you get is the
full and latest version released as of the date above.

Contributors to the development of GRAPHICA are entitled to mail
support, a copy of the latest version and a printed manual.
Please tell me the version number of your copy of GRAPHICA when
you send in your contribution.  My address can be found near the
end of this file.


▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀


MANUAL SUMMARY
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

Chapter 1: INTRODUCTION  Contains information concerning
           installation and hardware requirements.

Chapter 2: GETTING STARTED  Defines the fundamental elements
           common to all plots, defines the manual usage
           and presents a description of the command syntax.

Chapter 3: TUTORIAL  Takes the user through a series of
           short lessons to get familiar with GRAPHICA.

Chapter 4: COMMAND REFERENCE  Gives a list of all the commands
           understood by GRAPHICA.

Chapter 5: ADDITIONAL INFORMATION  Provides additional
           information on program access, reporting bugs,
           and other concepts useful to run GRAPHICA.

CONTRIBUTIONS
SHAREWARE DISTRIBUTION


TABLE OF CONTENTS
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

Chapter 1. INTRODUCTION

          1.1  Overview
          1.2  Disclaimer
          1.3  Files
          1.4  Equipment Requirements
          1.5  Installation

Chapter 2  GETTING STARTED

          2.1  Overview
          2.2  Document Conventions
          2.3  Starting Up and Exiting
          2.4  For Beginners
          2.5  Errors

Chapter 3  TUTORIAL

          3.1  Introduction
          3.2  Entering Commands
          3.3  Plotting Functions
          3.4  Plotting Data
          3.5  Plotting Data Files
          3.6  Plotting Parametric Curves
          3.7  Using Script Files
          3.8  Multiple Graphs on one Page
          3.9  Importing GRAPHICA Plots into WordPerfect

Chapter 4  COMMAND REFERENCE

Chapter 5  ADDITIONAL INFORMATION

          5.1  Mathematical Expressions
          5.2  Environment Variables
          5.3  Startup File
          5.4  Comments
          5.5  Text Control Sequences
          5.6  User-Defined Functions and Variables
          5.7  Bug Reporting


Chapter 1  INTRODUCTION
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

1.1  Overview
─────────────

GRAPHICA is a command-driven interactive graphics program for
making presentation quality graphs on a computer.  This two-
dimensional data plotting system is designed specifically for
scientific and engineering applications.  GRAPHICA is SHAREWARE,
i.e. it's user-supported.  GRAPHICA is easy to use, interactive,
and powerful.  With GRAPHICA, you can:

     o   plot functions or data files
     o   evaluate and plot mathematical expressions
     o   fit spline or polynomials to data
     o   display and print a graph on hardcopy devices
     o   export graphs in HPGL, PostScript or other formats
     o   draw text in roman, greek and cyrillic fonts
     o   get online help


1.2  Disclaimer
───────────────

The authors have made their best effort in producing this
software, but hereby disclaim all warranties.  The authors will
not be liable for any damages arising from the use or misuse of
GRAPHICA.  The person using the software bears all risk as to
the quality and performance of the software.  The program is
provided as is.


1.3  Files
──────────

GRAPHICA consists of the following files:

          GRAPHICA.EXE     main program
          GRAPHICA.HLP     help file
          GRAPHICA.DOC     user manual (this file)
          README.1ST       quick instructions
          HISTORY.DOC      log of latest changes
          EXAMPLES.ZIP     an archive containing

          *.PLT            sample input files
          *.DAT            data files


1.4  Equipment Requirements
───────────────────────────

GRAPHICA normally detects automatically what graphics monitor
hardware is present in order to preview graphs.  In general, you
basically need the following items:

          Computer:          IBM PC,XT,AT or compatibles

          Disk Drives:       2 floppy drives or 1 floppy drive/hard drive

          Memory:            640K Bytes

          Video Cards:       CGA, EGA, VGA or compatible adapter
                             Hercules Monochrome Adapter or compatible

          Hardcopy:
          - Plotters         HP7475A or HPGL compatible
          - Printers         Epson 80 and 100 series
                             Panasonic 1080i or equivalent

          Other Output:      PIC
                             HPGL
                             PostScript


1.5  Installation
─────────────────

There are no special installation requirements.  The simplest
procedure is to make a new directory on your hard disk, and to
copy all of the files there.  You may wish to put the GRAPHICA
directory on your path, or to copy the files to a RAM disk.

Let's suppose you wish to install GRAPHICA into a directory
called GRAPH.  To create the directory, simply do the following:

          C:\md graph
          C:\cd graph

If you have changed your system prompt with $P$G (as part of
your AUTOEXEC.BAT file, for example), the prompt should show:

          C:\GRAPH>

GRAPHICA should have been distributed as one file, called
GRPHCA22.ZIP or GRPH22.ZIP.  If so, then all files will have
to be extracted.  To do this run PKUNZIP or equivalent program
on the command line.  If you received GRPHCA22.ZIP, do:

          C:\GRAPH>pkunzip grphca22

All the GRAPHICA files will be put in this directory and you are
ready to start graphing.


Chapter 2  GETTING STARTED
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

2.1  Overview
─────────────

GRAPHICA is an interactive computer program which accepts
English sentence specifications of graphs, and, from those
specifications, produces publication quality pictures.  This
manual describes how to use GRAPHICA.  The specifications that
the user provides are referred to as "commands" or "statements".

Final graphs are of publication quality and may be fitted to
pages with existing text thereby eliminating costly reproduc-
tions (photocopying and reduction).

The user operates the program through a set of problem oriented
language (POL) commands.  Each command consists of keywords and
data values separated by blanks or commas.  This requires
minimum data input and enables simple and efficient graphing.
For example, if the user enters:

          map x 0,10 y 0,100

GRAPHICA determines that the user wants the x-axis range set from
0 to 10 and the y-axis range set from 0 to 100.  The user must
separate entities in a command with blanks or commas.  In this
manual, blanks are not explicitly indicated.

GRAPHICA capabilities include:

          - multiple curve plotting and graphs
          - axis drawing with labels and scaled divisions
          - log-log, semilog, probability and linear plots
          - graph titles and legends
          - lettering in five fonts and different sizes
          - hardware and software character generation
          - 3 units of measure (in, cm, mm)


2.2  Document Conventions
─────────────────────────

Input to GRAPHICA is in the form of a problem oriented language
(POL) designed specifically for graphing purposes.  The
following is a description of the conventions used within the
manual to explain GRAPHICA commands.

The appearance within a GRAPHICA command of a descriptor of the
form <integer> implies that the user is to enter an item of data
within that position in the statement of the class described by
the descriptor (in the above example, an integer).  The command

          divisions x <integer>,<integer>

implies that the word divisions is to be followed by the word x
and two integers such as 2 or 3, and that the statement entered
by the user as input data should be of the form

          divisions x 2,2

The following are definitions of most of the descriptors used
within the language.  Those not described below are ex- plained
when they first occur in the text.

<integer> a series of digits optionally preceeded by a plus or a
          minus sign.  Examples are 121, +300, -410.

<real> a series of digits with a decimal point included, or a
          series of digits with a decimal point followed by an
          exponent indicating a power of 10.  Real numbers may be
          optionally signed.  Examples are 1.0, -2.5, 3.6E+10.

<value> is either an integer or a real number.

'string' is any textual information enclosed within a pair of
          apostrophes (') or quotes (").  An example is 'Are you
          following this so far?'

As noted above, input to GRAPHICA is a series of English- like
commands.  Many of the words or phrases in these commands are
optional and are permitted primarily for readability or are used
to specify options within a command.  The curly braces {} denote
these optional items.

Each command is entered on a new line.  Commands can be entered
in lower case, upper case, or both.  Only the first significant
characters of a command are needed.  A line starting with a left
square bracket [ or a # will be treated as a comment line.
Also, anything after those two characters in a line will be
treated as a comment (see section 5.5).

Items such as <integer> shown in the command definitions must
always be replaced by an integer.  Undesignated items such as
<minimum>, <maximum>, etc. can be replaced by either an integer
or a real.  For example,

          divisions x2 <integer>,<integer>

can be specified as

          div x2 3 2
whereas
          map x <minimum value> <maximum value>

can be entered as

          map x 20 30
or
          map x 20.0 30.0

Sometimes keywords in a command line can be entered in any order
(except the very first one, of course).  For instance,

          plot add x connect y

will plot the X/Y data connecting all points and adding symbols.

In many commands, items may be repeated or more than one word is
acceptable in a given position within a command.  The choices
are listed enclosed in curly brackets '{}'.  For example, the
command definition

          draw {x} {y} {x2} {y2} {mask} {reflect}

indicates that the user may enter commands like

          draw x reflect y2 reflect
          draw x y
          draw y reflect x2 mask.

Similarly,

          paper {size} <horizontal value> {by} <vertical value>

can be written as

          paper size 11.0 by 8.5
          pap 11.0 8.5
or
          paper 11 by 8.5

In order to be more descriptive within the command definitions,
actual data items (items enclosed within '<>') are sometimes
described in terms of their physical meaning and followed by the
type or class of data item which can be used in the command.
For example, a command definition of the form

          input {from} {file} <filename>

implies that the data item following the word input is the name
of a file.  For example, acceptable commands would be

          input 'myfile.p'
          input from 'graph.dat'

Filenames or labels are not acceptable if they are not enclosed
within apostrophes or quotes.  Examples of commands with
incorrect labels or filenames are

          input from my data
          label top you*beast!
          xlabel honey.pie


2.3  Starting Up and Exiting
────────────────────────────

GRAPHICA can be run from any directory as long as GRAPHICA.EXE
is placed in the directory search path.  To start the plotting
system, simply type graphica at the DOS prompt:

          C:\graphica

GRAPHICA takes a few seconds to load into memory, and when the
graphica> prompt is displayed, the program is ready for your
input.  To exit, type quit or exit at the GRAPHICA command
level.

          graphica>quit

and you're back at the DOS prompt.


2.4  For Beginners
──────────────────

For a quick demonstration of GRAPHICA's main capabilities, run
GRAPHICA and then load some of the sample script files (*.PLT).
For example,

          C:\GRAPH\graphica (press return)
          graphica>load 'demo' (press return)

Alternatively, command-line arguments may be names of files
containing GRAPHICA commands.  Then, for example,

          C:\GRAPH\graphica demo

is another way of running the demo above.


2.5  Errors
───────────

Error messages are self-explanatory.  If an error is detected
while parsing a command or a script file, GRAPHICA will inform
you with a beep and message.


CHAPTER 3  TUTORIAL
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

3.1  Introduction
─────────────────

Welcome to the GRAPHICA tutorial.  A plot is a graphic image
used to present information in a visual manner.  The components
of a graphic image are:  lines, markers, text strings, polygons,
etc.  The basic ingredients of a plot are:  a page, a subplot
area and data points.  The data points are plotted using
symbols, characters or simple dots.  Data points and curves are
drawn or plotted on a grid space formed by Cartesian coordinate
axes.  The horizontal line is the x-axis and the vertical line,
the y-axis.

A graph is made with GRAPHICA by either loading an existing
script file from the disk, or by creating a new graph through
the command line.  This section explains how to create graphs.

All commands may be abbreviated, as long as the abbreviation is
not ambiguous.  Any number of commands may appear on a line,
separated by semicolons.  A file is loaded with the load
command.

Commands may extend over several input lines, by ending each
line but the last with a backslash (\).  The backslash must be
the last character on each line.  The effect is as if the
backslash and newline were not there.  Commenting out a
continued line comments out the entire command.


3.2  Entering Commands
──────────────────────

For help on any topic, type help followed by the name of the
topic at the graphica> prompt.

Let's get started.  Let's assume that you have copied all the
GRAPHICA files in a directory called GRAPH.  Start GRAPHICA by
entering graphica at the DOS prompt and pressing return:

          C:\GRAPH>graphica

The screen will clear, there will be a brief notice and you'll
be at the graphica> prompt:

          graphica>

Now you are about to begin making scientific graphs.

The plot command is the heart of GRAPHICA.  It is used to plot
data, functions and datafiles.  We will be using it a lot in the
next few pages.

Anytime you are ready to type in the next GRAPHICA command and
your screen shows a plot (in other words, you are in graphics
mode), just press any key or start typing the command in.  At
the graphica> prompt, you can always type show to have a look at
what you have plotted on the screen so far.


3.3  Plotting Functions
───────────────────────

To plot a sine wave, enter the following command at the
graphica> prompt:

          graphica>plot sin(x)

Within a few seconds, a graph of sin(x) as a function of x will
be plotted.  Press any key and then enter:

          graphica>draw x y

The x and y axes will be drawn.  The x axis will range from -10
to 10, since that is the default range.

You can plot functions that have singularities.  GRAPHICA will
try to choose the appropriate y scale.  Enter:

          graphica>clear

to sort of clear your graphics slate.  Then enter:

          graphica>samples 300
          graphica>plot tan(x)

The samples command simply tells GRAPHICA that we would like to
plot more points of the function that the default of 150.  After
that, the plot command plots the function.  To draw the axes, do:

          graphica>draw x y

You can give a list of functions to plot all at once.  Go ahead
and clear everything by entering:

          graphica>clear

Then, map the x-axis with the following command:

          graphica>map x 0 2*pi

To actually plot the functions, enter:

          graphica>plot sin(x), sin(2*x), sin(3*x)

And to draw the axes:

          graphica>draw x y

GRAPHICA always tries to plot functions as smooth curves.  As a
result, in places where your function wiggles a lot, you may
adapt GRAPHICA's sampling of your function to the form of the
function (we did that by giving the samples command at the
beginning of this section.)  Since GRAPHICA can only sample
your function at a limited number of points, it can sometimes
miss features of the function.  By increasing samples, you can
make GRAPHICA sample your function at a larger number of points.
Of course, the larger you set samples to be, the longer it will
take GRAPHICA to plot any function, even a smooth one.

The function sin(1/x) wiggles infinitely often when x is near
zero.  GRAPHICA can never sample the infinite number that it
would need to reproduce the function exactly.  As a result,
there are slight glitches in the plot.  Go ahead and try it:

          graphica>clear
          graphica>map x -1,1
          graphica>plot sin(1/x)
          graphica>draw x y

Now you have seen how to plot functions.  See section 5.1 for a
more detailed explanation about mathematical expressions.


3.4  Plotting Data
──────────────────

You may combine two GRAPHICA commands, plot and data, to plot
data points.  For example:

          graphica>clear
          graphica>data
          data>2 3
          data>5 4
          data>6 4
          data>7 5
          data>5 3
          data>end
          graphica>plot x y add
          graphica>draw x y

This sequence of commands will result in a simple graph with
both axis autoscaled.  See the map command for more details on
how to change the x-axis scale in the plot.


3.5  Plotting Data Files
────────────────────────

Data may also be plotted by retrieving the information from a
data file.  There are a couple of ways of doing this.  The first
is by simply specifying:

          graphica>clear
          graphica>data 'bob.dat'

where bob.dat contains 3 columns of numbers.  To plot the
data, you can do:

          graphica>plot data

which will plot the first 2 columns.  To draw the axes:

          graphica>draw x y

Using the other method, you can plot a datafile directly:

          graphica>clear
          graphica>plot 'bob.dat'

and now the axes:

          graphica>draw x y

The first method allows you to read in several columns of data
and then choose which one will be plotted (see column in the
reference section.)  By default, specifying plot data simply
plots the first two columns of data as x versus y.


3.6  Plotting Parametric Curves
───────────────────────────────

In a parametric plot, you give both the x and y coordinates of
each point as a function of a third parameter, say t.

Let us construct a parametric plot.  In this example, the
parametric curve made by taking the x coordinate of each point
to be sin(t) and the y coordinate to be sin(2*t):

          graphica>clear
          graphica>parametric plot t 0,2*pi sin(t) sin(2*t)
          graphica>draw x y


3.7  Using Script Files
───────────────────────

Every graph in this documentation can be readily reproduced from
the script files provided in the GRAPHICA package.  A script
file is simply a text file containing valid GRAPHICA commands.
The script file can be executed by the load or input command.
The name of the input file must be enclosed in single or double
quotes:

          graphica>clear
          graphica>load 'torp.plt'


3.8  Multiple Graphs on one Page
────────────────────────────────

With GRAPHICA, you may plot as many graphs on one page as you
wish by changing the subplot area.  Try this:

          graphica>clear
          graphica>load 'rocha.plt'

Several axes have been defined, x and y axes with labels, a y2
axis without labels, etc.  The data shown is actual experimental
data obtained by a doctoral student and the graph is part of his
dissertation.

You may now quit GRAPHICA by typing exit at the graphica> prompt.


3.9  Importing GRAPHICA Plots into WordPerfect
──────────────────────────────────────────────

This document was prepared using WordPerfect 5.1.  The plots
were produced with GRAPHICA, exported using HPGL output and
imported into WordPerfect.  Once a graphic has been imported
into WordPerfect, you can move it, scale it, rotate it, add
captions, etc.  Let's create a graph with GRAPHICA and retrieve
it into a WordPerfect document step by step.

There is a file in your distribution disk called ris108.plt.
Start GRAPHICA:

          C:\GRAPH>graphica

and load the script file:

          graphica>load 'ris108.plt'

The screen will clear and a plot will be drawn.  In fact, this
plot makes use of font 5 (complex cyrillic).  The graph was
created after one in a russian text dealing with petroleum
chemistry (I thought it might draw your attention).

Now press any key and enter:

          graphica>dump hpgl 'ris108.hpg'

The dump command will create a file called ris108.hpg containing
HPGL commands.  You may later send this file to a plotter or
pull it into any of the many programs that accept HPGL commands.
Now, exit GRAPHICA by typing:

          graphica>quit

and start WordPerfect:

          C:\GRAPH>wp

When the screen clears, do the following:

          1) press Alt-F9 (for the graphics menu)
          2) type 1 (for figure)
          3) select 1 (for create)
          4) select 1 (for filename)
          5) enter ris108.hpg (to read the file in, no quotes)

WordPerfect will retrieve the HPGL information into a graphic
box immediately.  You can edit the graph further within the
graphics menu:

          6) press 9 (for edit)

or simply view the graph:

          7) press F7 (to exit the graphics menu)
          8) press shift-F7 (for print)
          9) press 6 (for view document)

and you have successfully imported a GRAPHICA plot into a
WordPerfect document.


CHAPTER 4  COMMAND REFERENCE
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

This chapter gives an alphabetical lookup for all the GRAPHICA
built-in commands.  Here are all the supported commands:


ARROW                  Plot an Arrow at the End of a Line
AUDIT                  Set Command Trace
AUTOSCALE              Set Axis Autoscaling
AXES                   Draw One or More Axes
BACKGROUND             Specify Background Color
BEEP                   Turn beep on and off
CHARACTER              Set Character Attributes
CHARACTER FONT         Change the Character Font
CHARACTER GAP          Change the Character Gap
CHARACTER RATIO        Change the Character Ratio
CHARACTER SIZE         Change the Character Size
CHARACTER SLANT        Set the Character Slant
CD                     Change the Working Directory
CIRCLE                 Draw a Circle
CLEAR                  Erase Output Device
COLUMN                 Assign Data Columns to Axes
DATA                   Read Data from Terminal or a File
DEL                    Delete a file
DIGITIZE               Establish an x-y position
DIR                    List a directory
DIVISIONS              Set Number of Axis Divisions
DRAW                   Draw an Axis
DUMMY                  Specify Dummy Variable
DUMP                   Generate Hardcopy Output
ECHO                   Echo Typed Commands
EXIT                   Exit GRAPHICA
EXPONENT               Select Format in Log Labels
FORMAT                 Specify Axis Label Formats
FRAME                  Draw a Frame
GRID                   Draw a Grid
HELP                   Display On-line Help
LABEL                  Draw a Label
LEGEND                 Draw a Legend
LINE                   Draw a Line
LOAD, INPUT            Specify an Input File
LOCATION               Specify Type of x/y Position
MAP                    Specify the Limits of an Axis
MASK                   Mask a Rectangular Area
MEMORY                 Give the Amount of Memory Left
ORIGIN                 Specify Axis Origin
OUTPUT                 Specify Output Terminal
PAPER SIZE             Specify Paper Size
PARAMETRIC PLOT        Plot a Parametric Curve
PAUSE                  Pause and/or Wait for User Response
PEN                    Specify a Pen Parameter
PLOT                   Plot a Datafile, Curve or Function
PLOTTING SEQUENCE      Select a Plotting Sequence
POLYFIT                Generate a Polynomial by Least Squares
PRINT                  Print the Value of an Expression
PWD                    Print Current Working Directory
QUIT                   Exit GRAPHICA
RECTANGLE              Draw a Rectangle
SAMPLES                Specify Sampling Rate
SHADE                  Shade a Specified Set of Data
SHELL                  Spawn a DOS Shell
SHOW                   Show a Parameter
SPLINE                 Fit Data to a Spline
SUBPLOT AREA           Specify Area Where Plot Will Go
SUB/SUPERSCRIPT        Set the Sub/Superscript Size
SYMBOL                 Select a Plotting Symbol
TERMINAL               Specify Output Terminal Type
TIC                    Specify Tic Mark Size and Direction
TITLE                  Draw a Centered Axis Label
TYPE                   Type a file
UNIT                   Specify Drawing Units
VIEW                   Move Paper to View Plotter Output
X,Y,X2,Y2              Specify Axis Type
X,Y,X2,Y2LABEL         Draw a Centered Axis Label


The file GRAPHICA.HLP (included with this package) is used by
the program to give you online help.  It is an ASCII file and
may be printed.  It contains detailed information about each of
the above commands, their features and how to use them.


CHAPTER 5  ADDITIONAL INFORMATION
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

5.1  Mathematical Expressions
─────────────────────────────

In general, any mathematical expression accepted by C, FORTRAN,
Pascal, or BASIC is valid.  The precedence of these operators is
determined by the specifications of the C programming language.
White space (spaces and tabs) is ignored inside expressions.

Complex constants may be expressed as the {<real>,<imag>}, where
<real> and <imag> must be numerical constants.  For example,
{3,2} represents 3 + 2i; {0,1} represents `i` itself.  The curly
braces are explicitly required here.

functions
─────────

All functions in GRAPHICA accept integer, real, and complex
arguments, unless otherwise noted.

abs(z) returns the absolute value of the real or complex number
z.  The returned value is of the same type as the argument.  For
complex arguments, abs(z) is defined as the length of z in the
complex plane [i.e.,  sqrt(real(z)**2 + imag(z)**2) ].

acos(z) returns the arc cosine (inverse cosine) of z.  All
results are given in radians.

arg(z) returns the phase angle of a complex number z, in
radians.  The result is always between -π and π.

asin(z) returns the arc sine (inverse sine) of z.  All results
are given in radians.

atan(z) returns the arc tangent (inverse tangent) of z.  All
results are given in radians.

besj0(z) returns the j0th Bessel function of z.  besj0 expects z
to be in radians.

besj1(z) returns the j1st Bessel function of z.  besj1 expects z
to be in radians.

besy0(z) returns the y0th Bessel function of z.  besy0 expects z
to be in radians.

besy1(z) returns the y1st Bessel function of z.  besy1 expects z
to be in radians.

ceil(z) returns the smallest integer greater than z.  For
complex numbers, ceil returns the smallest integer greater than
the real part of z.

cos(z) returns the cosine of z.  cos expects z to be in radians.

cosh(z) returns the hyperbolic cosine of z.  cosh expects z to
be in radians.

erf(z) returns the error function of z.  erf(z) is the integral of the
Gaussian distribution.  The error function is central to many calculations
in statistics.

erfc(z) returns the complementary error function of z.  erfc(z) is
simply 1.0 - erf(z), where erf(z) is the integral of the Gaussian
distribution.

exp(z) returns the exponential function of z (e raised to the
power of z).

floor(z) returns the greatest integer less than or equal to z.
For complex numbers, floor returns the largest integer not
greater than the real part of z.

imag(z) returns the imaginary part of z as a real number.

int(z) returns the integer part of z, truncated toward zero.

ln(z) returns the natural logarithm (base e) of z.

log(z) returns the logarithm (base 10) of z.

real(z) returns the real part of z.

sgn(z) returns 1 if z is positive, -1 if z is negative, and 0 if
z is 0.  If z is a complex value, the imaginary component is
ignored.

sin(z) returns the sine of z.  sin expects z to be in radians.

sinh(z) returns the hyperbolic sine of z.  sinh expects z to be
in radians.

sqrt(z) returns the square root of z.

tan(z) returns the tangent of z.  tan expects z to be in
radians.

tanh(z) returns the hyperbolic tangent of z.  tanh expects z to
be in radians.

operators
─────────

All operators in GRAPHICA accept integer, real, and complex
arguments, unless otherwise noted.  The ** operator (exponentia-
tion) is supported, as in FORTRAN.

Parentheses may be used to change order of evaluation.

The following is a list of all the binary operators and their
usage:

         symbol             example              explanation

          **                 a**b                 exponentiation
          *                  a*b                  multiplication
          /                  a/b                  division
          %                  a%b                * modulo
          +                  a+b                  addition
          -                  a-b                  subtraction
          ==                 a==b                 equality
          !=                 a!=b                 inequality
          &                  a&b                * bitwise AND
          ^                  a^b                * bitwise exclusive OR
          |                  a|b                * bitwise inclusive OR
          &&                 a&&b               * logical AND
          ||                 a||b               * logical OR

          (*) Operator requires integer arguments.

Logical AND (&&) and OR (||) short-circuit the way they do in C.
That is, the second && operand is not evaluated if the first is
false;  the second || operand is not evaluated if the first is
true.

Multiplication must be explicitly noted with the asterisk;
adjacent parenthetical terms such as (a+b)(c-4) are not
automatically multiplied.

          symbol             example              explanation

           \:                 a\b:c              * ternary operation

          (*) Operator requires an integer argument.

The ternary operator evaluates its first argument (a).  If it is
true (non-zero) the second argument (b) is evaluated and
returned, otherwise the third argument (c) is evaluated and
returned.

The following is a list of all the unary operators and their
usage:

          symbol             example              explanation

           -                  -a                   unary minus
           ~                  ~a                 * one's complement
           !                  !a                 * logical negation
           !                  a!                 * factorial

          (*) Operator requires an integer argument.

The factorial operator returns a real number to allow a greater
range.


5.2  Environment Variables
──────────────────────────

An environment variable is used to specify from DOS certain
parameters of program operation.  The "environment" is really
just a common area of memory that programs can write to and read
from.  Some programs are geared to look specifically at the
environment to find particular data important to their
operation.  If we were to look at the DOS environment (by typing
the SET command at the DOS prompt), we might see a listing
similar to the one below:

          COMSPEC=C:\COMMAND.COM
          PATH=C:\;C:\DOS;C:\UTIL

Other values might be present, like PROMPT=$P$G, and more
depending on the types and kinds of software you are running.
Some programs ask you to place a variable into the environment
equal to a certain value so that they can find support files
which could not be found otherwise.

Environment variables are specified before running GRAPHICA.
They can be specified directly from DOS, from within the
AUTOEXEC.BAT file, or from within any batch file.

The command for setting an environment variable is:

          SET PARAMETER=PARAMETER VALUE

A number of shell environment variables are understood by
GRAPHICA.  None of these are required, but may be useful:

          - GRAPTERM
          - GRAPDUMP
          - GRAPHELP
          - GRAPHICA

If GRAPTERM is defined, it is used as the name of the terminal
type to be used.  This overrides any terminal type sensed by
GRAPHICA on start up, but is itself overridden by the
GRAPHICA.INI (or equivalent) start-up file, and of course by
later explicit changes.

GRAPHELP may be defined to be the pathname of the HELP file
(GRAPHICA.HLP).  GRAPHICA is used as the name of a directory to
search for a GRAPHICA.INI file if none is found in the current
directory.  COMSPEC is used for the SHELL command.

Examples:

          C:\SET GRAPTERM=hpgl            (sets the terminal type)
          C:\SET GRAPHELP=C:\plot         (location of the help file)
          C:\SET GRAPHICA=C:\plot         (location of the .INI file)


5.3  Startup File
─────────────────

When GRAPHICA is run, it looks for an initialization file to
load.  This file is called GRAPHICA.INI.  If this file is not
found in the current directory, the program will look for it in
your home directory (the environment variable GRAPHICA should
contain the name of this directory).

If the initialization file is found, GRAPHICA executes the
commands in the file.  This is most useful for setting your
terminal type and defining any functions or variables which you
use often.


5.4  Comments
─────────────

Comments are supported as follows:  a # or [ may appear in most
places in a line and GRAPHICA will ignore the rest of the line.
It will not have this effect inside quotes or inside numbers
(including complex numbers).

Examples:

          graphica>[ test file ]
          graphica>echo           # echo all commands
          graphica># map axes
          graphica>map x 0 10 y 0 10


5.5  Text Control Sequences
───────────────────────────

Description:

Text primitives generate a string of characters on a display
device in a specific location in the world coordinate system.
The character string may comprise letters, numerals, and
symbols.  Text primitives provide a method for labeling and
clarifying a graphical image.

This section describes the control sequences which are
accessible when specifying a string label.  GRAPHICA recognizes
\ as a special character used to signal the start of an escape
sequence.  There are two sorts of escape sequences, those that
take an argument and those that do not.

Two escape sequences do not take an argument:

          \U move up half a character size
          \D move down half a character size

The following take an integer argument immediately after the
escape sequence and a space after it to delineate the end (the
space is not printed):

          \Cn    set color to n
          \C-1   reset color to the default
          \Fn    set font to n
          \F-1   reset font to the default
          \Sn    set character size to n
          \S-1   reset character size to the default
          \Ln    set character slant to n degrees
          \L-1   reset character slant to the default slant
          \An    print ascii n
          \rn    save current position in register n
          \Rn    restore position from register n

Examples:

to print greek characters such as in 'beta = x + lambda':

          label '\F2 b\F1 = x + \F2l'

to label the x-axis with 'velocity U sub f':

          xlabel 'velocity, U\Dsub'

to place a top label of 'stress in dynes per cm squared':

          top label 'stress (dyn\cm\U2\D)'

to get 'x squared plus y squared':

          label 'x\U2\D + y\U2'

and finally, an advanced example.  To get 'A sub b sup beta':

          label 'A\r1 \Db\R1 \U\F2 b'

This last example is translated as: do A, save this spot, go down
half, do b, restore the saved spot, go up half, switch to font 2
(greek simplex), do beta.  Notice the use of registers to stack
characters on top of each other.

To get a backslash, you'll have to use \\.


5.6  User-Defined Functions and Variables
─────────────────────────────────────────

User-defined function syntax:

          <function-name> ( <dummy-var> ) = <expression>
          show functions

where <expression> is defined in terms of <dummy-var>.

User-defined variable syntax:

          <variable-name> = <constant-expression>
          show variables

Description:

You may define your own functions and variables.  User-defined
functions and variables may be used anywhere an expression is
called for.  Variable and function names are case sensitive;
thus "A" is not equivalent to "a".  A function refers to a
general expression and can take one argument (dummy variable).

Examples:

          graphica>w = 2
          graphica>q = floor(tan(pi/2 - 0.1))
          graphica>f(x) = sin(w*x)
          graphica>sinc(x) = sin(pi*x)/(pi*x)
          graphica>delta(t) = (t == 0)
          graphica>ramp(t) = (t > 0) ? t : 0

The following variables have already been defined for you:

          pi    = 3.14159
          e     = 2.71828
          gamma = 0.57721
          goldr = 1.61803


5.7  Bug Reporting
──────────────────

GRAPHICA is under constant revision, updating and being given
expanded capabilities.  Prior to each release, I strive to
verify new features and bug fixes through testing.  However, as
inevitably happens with any software, some bugs do survive and
show up in user runs.  Users can aid in the problem fixing
process by following the guidelines below:

a) Report any unusual messages, computed results, format
   overflows, etc. even though the program appears to have
   terminated normally.

b) For any abnormal program termination, save the input file and
   all output obtained by running the program.

Reported problems will be fixed as quickly as possible.  In most
instances, alternate methods or techniques of plot formulation
and input are available to permit graphing despite the bug.  All
problems encountered with GRAPHICA should be reported to the
address below.


CONTRIBUTIONS
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

If you like the program and find it useful, you can support its
continued development by sending me a contribution of HFL 45.-
(dutch guilders) or US$25 (US dollars).

A contribution will entitle you to mail support, a copy of the
latest version and a printed manual.  More to the point, though,
it'll make you feel good.  I've not infested the program with
any beg notices, crippled it or had it verbally insult you after
a few days.  I trust you to support GRAPHICA if you like it.

If you want to see additional features in GRAPHICA, please send
in a contribution.  Feel free to contact me for any reason.

My address is:

          Antonio Montes
          Postbus 13
          2350 AA Leiderdorp
          The Netherlands

e-mail:
          CompuServe 71031,1162
          internet: [e-mail]


EUROPEAN USERS
──────────────

In addition to sending me your name, address and size of disk
you need, you may contribute in one of three ways:

1) send a eurocheque for HFL 45.00 to my address.
2) wire HFL 45.00 to the Postbank Giro Account 3366191 in my name.
3) send HFL 45.00 in cash in an envelope at your own risk.


OTHER USERS
───────────

In addition to sending me your name, address and size of disk
you need, you may contribute by please sending a check in US
funds for the equivalent of US$25.

You can send me a check from any bank in the United States.
I have a US account and will have no problem making a deposit.

If you send a check drawn on an international bank, make sure
that it will be negotiable in the United States.  If there's
no bank routing number along the bottom of the check, it will
not clear.


SHAREWARE DISTRIBUTION
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

I don't have the facilities to send out disks in response to all
the shareware distributors requesting a disk.  If you're a
fairly large shareware distributor, I can provide you with a
floppy disk.

If you'd like to request a disk, please send me a copy of your
current catalog.  Your catalog must satisfy the following
requirements:

- It must be commercially printed.  I am unable to accept
  catalogs on disk, catalogs which have been duplicated with a
  photocopier or mimeograph machine or catalogs which have been
  created using a dot matrix printer.

- It must be comprised of descriptive listings for the shareware
  it offers.  Such a listing should be at least four or five lines
  describing the software in question.

- It must explain in a clear and prominent way that the software
  being offered in the catalog is user supported software, that
  paying your company for it does not constitute registering it
  and that users who buy your disks and use the programs on them
  are expected to register their software if they continue to use it.

- If you don't have a catalog which meets the above description,
  you can obtain a copy of the shareware disk for $10.00 (US).

Please note that I will send you one disk.  I can send you
updates of the software if you're able to provide me with an
account of how many copies of the package you have distributed.